---
title: AsyncStorage
---

[`AsyncStorage`](https://github.com/react-native-community/async-storage) is a (formerly built-in) API for client-side data persistence. Here we'll cover basic usage of the API and an example.

> Since this library includes native modules, if you're not using Expo, you'll need to update your `CocoaPods` on iOS. See the installation instructions: https://react-native-community.github.io/async-storage/docs/install

## API

The `AsyncStorage` API is promise-based. Getting and setting key-value pairs is asynchronous. All of the APIs can throw errors upon failure, which you'll want to handle!

The main APIs are:

- `getItem(key: string)` - Get the `value` stored at `key`. This will return a `Promise` containing a string, or null if no data has been stored yet for that `key`.
- `setItem(key: string, value: string)` - Store the `value` at `key`, replacing any existing value stored there.

These two APIs are frequently all you'll need, although there are more APIs for getting/setting multiple values and merging values if you have more advanced needs.

> The API operates on strings, but typically you'll use JSON: remember to call `JSON.stringify` before storing data and `JSON.parse` after retreiving it.

## Example

Let's look at an example of getting and setting a key-value pair in `AsyncStorage`.

This app contains:

- An `App` component thats loads the value at `STORAGE_KEY` into `name` using `useState` when it mounts. Every time you type your name in the input field and hit enter, we save `name` to `STORAGE_KEY`, as well as updating the value in `name`. Note that we also catch errors thrown when loading/saving.
- `Input.js`, a presentational `TextInput`-based component

<Example
  files={{
    'App.js': require('../../../examples/files/app/AsyncStorage').default,
    'Input.js': require('../../../examples/files/app/Input').default,
  }}
  modules={[
    {
      name: '@react-native-community/async-storage',
      url:
        'https://gitcdn.xyz/repo/dabbott/c808d04daf4d8d5477e911fe2bce2e63/raw/ef6952e3f4e9fdc6fcd0fc1cd199dda526d2d006/AsyncStorageInterop.js',
    },
  ]}
/>
